file BitMapLisp.txt Copyright (C) 1996 by John Montbriand.  All Rights Reserved.

ABOUT BITMAP...

    Copyright (C) 1996 by John Montbriand.  All Rights Reserved.
    
    Distribute freely in areas where the laws of copyright apply.

    Use at your own risk.
    
    Do not distribute modified copies.

    These various BitMap libraries are for free!

    This file describes the Macintosh Common Lisp interface
    to the bitmap routines.


ABOUT THE AUTHOR...

    Comments, questions, or suggestions are always welcome.

    John Montbriand                tinyjohn@sasknet.sk.ca
    P.O. Box. 1133
    Saskatoon Saskatchewan Canada
    S7K 3N2


WHY IS IT FOR FREE?

    none of your business,
    
    but if you have some business for me,  I'll see what I can do..


OUTLINE OF TOPICS

    INSTALLATION INSTRUCTIONS
    BITMAPS, WHAT ARE THEY?
    IMPLEMENTATION NOTES
    MATERIALS
    LEGAL STUFF
    FURTHER REFERENCE
    SERVICES PROVIDED (OVERVIEW)
    BE CAREFUL (CAVEATS)
    OTHER COOL THINGS YOU CAN DO
    OVERVIEW OF ROUTINES
    SPECIFIC ROUTINE DESCRIPTIONS


INSTALLATION INSTRUCTIONS

    To install the bitmaps package in your system, move the files
    BitMaps.lisp and BitMapsLib.o (found in the folder entitled
    'Library Folder Stuff') into the 'Library' folder inside of the
    MCL directory.

    Once this has been done, the bitmaps package can be conveniently
    loaded and imported into the current package using the following
    commands:

        (require :bitmaps)
        (use-package :bitmaps)
    
    see the file BitMapExamples.lisp for an example of how to load
    the bitmaps package once it has been correctly installed in the
    Library folder.


BITMAPS, WHAT ARE THEY?
    
    Well, they're like little black and white computer screens in memory
    that you can do drawing in before transfering the images you
    draw on them to the screen.  Drawing things off screen and then
    placing them on screen creates the feel of instantaneous, flicker
    free drawing.
    
    BitMaps are a data structure used to store black and white images
    off-screen.  You can use quickdraw to draw directly into bitmaps
    and create images for placement on the screen, or you can take
    images from the screen, place them in a bitmap, do various
    transformations to them, and then put them back on the screen.
    
    QuickDraw GrafPorts draw into BitMap structures, and, as a matter
    of fact, all screen drawing on early macintoshes was implemented
    through BitMaps that were memory mapped to the screen hardware.
    
    The big advantage:  BitMaps provide a way to do simple high quality
    graphics while at the same time requiring very little memory.


IMPLEMENTATION NOTES

    This implementation stores each bitmap in a single, contiguous,
    non-relocatable memory block refered to using a pointer.  The first
    14 bytes of the memory block contain the Bitmap data structure,
    while the remaining bytes are used to store the raster data.


MATERIALS

    The BitMap format itself is the copyright property of Apple
    computer and has been known to the public since 1983.
    
    The routines documented herein are the copyright property of
    John Montbriand.  I am making these routines available to the
    macintosh programming community because I feel it's about time
    someone did!  They're fun, easy to use, and practical.  I hope
    all who find them will use them well.

    Compiled and tested with MPW C, MWC, SC, MrC, MPW PPC, MCL2, MCL3.


LEGAL STUFF

    These libraries are provided for free and you may use them
    in any program you make;  however, if you're particular about
    having signed documentation that proves this fact in your posession
    then, as I would like to ensure these libraries are widely used,
    I would be glad provide such documents for you.
    
    I don't think this is entirly necessary, but I can understand
    that some folks feel quite strongly about such issues and prefer
    to do things in writing.
    
    If you would like for me to send you a signed document saying
    that you have license to use these routines in your programs,
    then send me a couple of bucks to cover postage and handling
    and I'll send you back a signed letter saying you have license
    to use these routines in any software you make.
    
    I think two or three dollars is fair as I don't really get a big
    thrill out of printing stuff out and mailing it, and that's usually
    enough to cover postage to anywhere in the world.  I s'pose you'd have
    to figure out how much it would cost for me to mail a letter to you
    from here in Canada.


FURTHER REFERENCE

    BitMap.h and BitMap.c contain routines for accessing and manipulating
    BitMap data stored in pointers.  For more information about BitMaps,
    offscreen drawing, pointers, C, etc..  refer to the following sources:
    
    "Bitmaps" (2-9) in the "Basic QuickDraw" chapter of Inside Macintosh:
    Imaging With QuickDraw by Apple Computer, Inc.  Addison-Wesley.
        A discussion of the Bitmap data structure and how it applies to
        GrafPorts.
        
    "Boolean Transfer Modes With 1-Bit Pixels" (3-8) in the "QuickDraw Drawing"
    chapter of Inside Macintosh: Imaging With QuickDraw by Apple Computer,
    Inc.  Addison-Wesley.
        BitMaps are 1-Bit Pixel data structures.  This part discusses the
        various transfer modes you can use while drawing into BitMaps.
    
    "Copying Bits Between Graphics Ports" (3-32) in the "QuickDraw Drawing"
    chapter of Inside Macintosh: Imaging With QuickDraw by Apple
    Computer, Inc.  Addison-Wesley.
        A discussion of the Bitmap data structure and how it applies to
        GrafPorts.
        
    "Copying Images" (3-112) in the "QuickDraw Drawing" chapter of
    Inside Macintosh: Imaging With QuickDraw by Apple
    Computer, Inc.  Addison-Wesley.
        A discussion of the CopyBits routine and the various parameter
        combinations you can use with it.  This is followed by
        a discussion of the CopyMask routine.

    Technical note #163 "Adding Color With CopyBits" by Chris Derossi
        A discussion of how to draw in colour using bitmaps.
    
    Technical note #193 "So Many Bitmaps, So Little Time" by Rick Blair
        A look at the BitMapToRegion routine.
    
    Technical note #41 "Drawing Into an Offscreen Bitmap" by
    Jim Friedlander & Ginger Jernigan
        A talk about offscreen bitmaps, and how to use them.
    
    Inside Macintosh: Memory by Apple Computer, Inc.  Addison-Wesley.
        A discussion of memory managment, pointers, what they are, and
        how to use them.
    
    The C Programming Language 2nd edition by Brian W. Kernighan
        and Dennis M. Ritchie.  Prentice Hall.
    
    Macintosh Common Lisp Reference

    Common Lisp 2nd edition by Guy L. Steele Jr. Digital Press.

    Comments for the routines provided herein have been included in the
    file BitMap.h.
    
    Also, there is a 411 help file.
    

SERVICES PROVIDED (OVERVIEW)

    - routines for creating bitmap structures in memory.
    
    - rotate functions for rotating bitmaps 90 degrees left and right,
    
    - flip functions for flipping bitmap data both vertically
    and horizontally,
    
    - a trace edges routine for tracing the edges of an image,
    
    - a rotation routine for rotating a bitmap to a particular angle,
    
    - a routine for duplicating bitmaps,
    
    - a routine for comparing bitmaps,
    
    - routines providing the painbucket tool and lasso tool effects,
    
    - transfer routines for transfering bitmap data to and from the
    PICT format,
    
    - a complete set of logical operations on bitmaps,
    
    - a complete set of pixel oriented routines for testing, setting,
    clearing, and toggling individual pixels in bitmaps,
    
    - routines and a macro allowing you to quickly and easily draw
    into bitmaps,
    
    - routines for copying bitmap images to the current grafport,


BE CAREFUL (CAVEATS)

    I think these routines are safe to use, but you should do your own
    testing.  I have provided the source code, and if you find any bugs,
    please let me know right away so I can provide corrections in
    future versions.
    
    I advertise a finder's fee of $10.00 cash for errors in any
    of my products.


OTHER COOL THINGS YOU CAN DO

    bitmaps provide a convenient, storage efficient way to
    implement zero - one adjacency matrices that are incredibly
    useful for working with directed graphs.


OVERVIEW OF ROUTINES

    creating your own bitmaps:
        (new-bitmap width height) -> a bitmap
        (kill-bitmap bitmap &rest other-bitmaps)
    
    rotating a bitmap image 90 degrees to the left or to the right:
        (rotate-bitmap-right bitmap) -> a bitmap
        (rotate-bitmap-left bitmap) -> a bitmap
   
    flipping a bitmap image horizontally or vertically:
        (flip-bitmap-vertically bitmap) -> a bitmap
        (flip-bitmap-horizontally bitmap) -> a bitmap
   
    rotating a bitmap image to a particular angle:
        (rotate-bitmap bitmap h-center v-center angle) -> a bitmap

    duplicating a bitmap:
        (duplicate-bitmap bitmap) -> a bitmap
        
    the paint bucket function:
        (paint-bucket-bitmap bitmap h v) -> a bitmap
    
    the lasso function:
        (lasso-bitmap bitmap) -> a bitmap

    the trace edges function:
        (trace-bitmap-edges bitmap) -> a bitmap

    transfer functions for converting to and from the PICT format:
        (picture-to-bitmap bitmap) -> a bitmap
        (bitmap-to-picture bitmap) -> a picture
    
    logical operations on bitmaps:
        (and-bitmaps bitmap-a bitmap-b) -> a bitmap
        (or-bitmaps bitmap-a bitmap-b) -> a bitmap
        (xor-bitmaps bitmap-a bitmap-b) -> a bitmap
        (complement-bitmap bitmap) -> a bitmap
    
    comparison:
        (equal-bitmaps bitmap-a bitmap-b) -> T or NIL
    
    pixel oriented functions:
        (test-bitmap-pixel bitmap x y) -> T or NIL
        (set-bitmap-pixel bitmap hpos vpos)
        (clear-bitmap-pixel bitmap hpos vpos)
        (toggle-bitmap-pixel bitmap x y) -> T or NIL
    
    routines for drawing into bitmaps:
        (with-focused-bitmap bitmap {form}*) -> bitmap    

    routines for copying bitmap data:
        (plot-bitmap bitmap hpos vpos mode)

    a routine for converting pascal strings into bitmaps:
        (string-to-bitmap the-string &optional the-font-spec) -> a bitmap
        
        
SPECIFIC ROUTINE DESCRIPTIONS


new-bitmap

    formal declaration:
        (new-bitmap width height) -> a bitmap
    
    arguments:
        width     the width of the requested bitmap
        height    the height of the requested bitmap
    
    return value:
        a pointer to a Bitmap data structure. 
        if an error occurs, NULL is returned.
        
    description:
        new-bitmap creates a new bitmap pointer with the requested
        dimensions.  The raster data is initialized to zeros, and if
        there is not enough memory to allocate the bitmap, NewBitMap
        will return NULL.
        
    example application:
        The following creates a new bitmap pointer 100 pixels wide
        and 200 pixels tall.
        
        (let (mybits)
           (setf mybits (new-bitmap 100 200))
           ...
           )
            
    notes:
        You can call #_DisposePtr to dispose of a bitmap pointer created by
        new-bitmap  The routine kill-bitmap calls #_DisposePtr.


kill-bitmap

    formal declaration:
        (kill-bitmap bitmap &rest other-bitmaps)
    
    arguments:
        one or more bitmaps
    
    return value:
        none.
        
    description:
        kill-bitmap disposes of bitmaps allocated by:
        
        new-bitmap, duplicate-bitmap, rotate-bitmap-right, rotate-bitmap-left,
        flip-bitmap-vertically, flip-bitmap-horizontally, rotate-bitmap,
        paint-bucket-bitmap, lasso-bitmap, trace-bitmap-edges,
        picture-to-bitmap, and-bitmaps, or-bitmaps, xor-bitmaps,
        complement-bitmap, or string-to-bitmap.
        
        It's your general all purpose bitmap disposal function.

    example application:
        The following creates a new bitmap pointer 100 pixels wide
        and 200 pixels tall and then disposes of it by calling kill-bitmap
        
        (let (mybits)
           (setf mybits (new-bitmap 100 200))
           ...
           (kill-bitmap mybits))
            
    notes:
        kill-bitmap simply calls #_DisposePtr.


rotate-bitmap-right

    formal declaration:
        (rotate-bitmap-right bitmap) -> a bitmap
    
    arguments:
        bits    a bitmap
    
    return value:
        a newly created bitmap pointer containing the image
        from the bitmap pointer parameter rotated 90 degrees
        to the right. 
        if an error occurs, rotate-bitmap-right will return the value NULL.
        
    description:
        rotate-bitmap-right creates a new bitmap containing the image
        stored in the parameter bitmap pointer rotated 90 degrees
        to the right.  The resulting bitmap is appropriately sized:
        i.e. if the source bitmap is 100 pixels wide and 200 pixels tall,
        then the result bitmap pointer will be 200 pixels wide and 100
        pixels tall.  

    example application:
        The example creates a new bitmap pointer containing the image
        stored in the original bitmap rotated 90 degrees to the right
        before copying the image to the current grafport.
        
        (prog (the-bits rotated-bits)
            
           (setf the-bits (new-bitmap 100 200))
           
           ;; normally, we'd draw an image on the bitmap here

           (setf rotated-bits (rotate-bitmap-right the-bits))
           
           (plot-bitmap rotated_bits 0 0 #$srcCopy)
           
           (kill-bitmap the-bits rotated-bits))
            
    notes:
        rotate-bitmap-right takes advantage of certain addressing and indexing
        possibilities offered by the arrangement of the raster data
        in memory.  It is faster than calling rotate-bitmap and specifying
        a 90 degree angle.


rotate-bitmap-left

    formal declaration:
        (rotate-bitmap-left bitmap) -> a bitmap
    
    arguments:
        bits    a bitmap pointer
    
    return value:
        a newly created bitmap pointer containing the image
        from the bitmap pointer parameter rotated 90 degrees
        to the left. 
        if an error occurs, rotate-bitmap-left will return the value NULL.
        
    description:
        rotate-bitmap-left creates a new bitmap containing the image
        stored in the parameter bitmap pointer rotated 90 degrees
        to the left.  The resulting bitmap is appropriately sized:
        i.e. if the source bitmap is 100 pixels wide and 200 pixels tall,
        then the result bitmap pointer will be 200 pixels wide and 100
        pixels tall.  

    example application:
        The example creates a new bitmap pointer containing the image
        stored in the original bitmap rotated 90 degrees to the left
        before copying the image to the current grafport.
        
        (prog (the-bits rotated-bits)
            
           (setf the-bits (new-bitmap 100 200))
           
           ;; normally, we'd draw an image on the bitmap here

           (setf rotated-bits (rotate-bitmap-left the-bits))
           
           (plot-bitmap rotated_bits 0 0 #$srcCopy)
           
           (kill-bitmap the-bits rotated-bits))
            
    notes:
        rotate-bitmap-left takes advantage of certain addressing and indexing
        possibilities offered by the arrangement of the raster data
        in memory.  It is faster than calling rotate-bitmap and specifying
        a -90 degree angle.


flip-bitmap-vertically

    formal declaration:
        (flip-bitmap-vertically bitmap) -> a bitmap
    
    arguments:
        bits    a bitmap pointer
    
    return value:
        a newly created bitmap pointer containing the image
        from the bitmap pointer parameter flipped upside down. 
        if an error occurs, flip-bitmap-vertically will return the value NULL
        
    description:
        flip-bitmap-vertically creates a new bitmap containing the image
        stored in the parameter bitmap pointer flipped upside
        down.  The resulting bitmap will be the same size as
        the original image.  

    example application:
        The example creates a new bitmap pointer containing the image
        stored in the original bitmap flipped upside down before
        copying the new flipped image to the current grafport.
        
        (prog (the-bits flippin-bits)
            
           (setf the-bits (new-bitmap 100 200))
           
           ;; normally, we'd draw an image on the bitmap here

           (setf flippin-bits (flip-bitmap-vertically the-bits))
           
           (plot-bitmap flippin-bits 0 0 #$srcCopy)
           
           (kill-bitmap the-bits flippin-bits))
            
    notes:
        none.


flip-bitmap-horizontally

    formal declaration:
        (flip-bitmap-horizontally bitmap) -> a bitmap
    
    arguments:
        bits    a bitmap pointer
    
    return value:
        a newly created bitmap pointer containing the image
        from the bitmap pointer parameter flipped horizontally. 
        if an error occurs, flip-bitmap-horizontally will return the value NULL.
        
    description:
        flip-bitmap-horizontally creates a new bitmap containing the image
        stored in the parameter bitmap pointer flipped horizontally.
        The resulting bitmap will be the same size as the original image.  

    example application:
        The example creates a new bitmap pointer containing the image
        stored in the original bitmap flipped horizontally before
        copying the new flipped image to the current grafport.
        
        (prog (the-bits flippin-bits)
            
           (setf the-bits (new-bitmap 100 200))
           
           ;; normally, we'd draw an image on the bitmap here

           (setf flippin-bits (flip-bitmap-horizontally the-bits))
           
           (plot-bitmap flippin-bits 0 0 #$srcCopy)
           
           (kill-bitmap the-bits flippin-bits))
            
    notes:
        none.


rotate-bitmap

    formal declaration:
        (rotate-bitmap bitmap h-center v-center angle) -> a bitmap
    
    arguments:
        bits      a bitmap pointer
        cx        the horizontal center of rotation
        cy        the vertical center of rotation
        angle     the angle (in degrees) to rotate the image. both positive
                  and negative values are ok.  This is an integer number.
                
    return value:
        a newly created bitmap pointer containing the image
        from the bitmap pointer parameter rotated around the center
        cx and cy angle degrees. 
        if an error occurs, rotate-bitmap will return the value NULL.
        
    description:
        rotate-bitmap creates a new bitmap containing the image from
        the parameter bitmap pointer rotated angle degrees about the
        center (cx, cy).  The resultant bitmap will have the same dimensions
        as the parameter bitmap regardless of the angle specified.

    example application:
        The example creates a new bitmap pointer containing the image
        stored in the original bitmap rotated 35 degrees to the right
        before copying the rotated image to the current grafport.
        
        (prog (the-bits round-bits)
            
           (setf the-bits (new-bitmap 100 200))
           
           ;; normally, we'd draw an image on the bitmap here

           (setf round-bits (rotate-bitmap the-bits 50 50 35))
           
           (plot-bitmap round-bits 0 0 #$srcCopy)
           
           (kill-bitmap the-bits round-bits))
            
    notes:
        rotate-bitmap has a speedy implementation built on top of the
        fixed math routines.  For more information about fixed math
        refer to the Mathematical and Logical Utilities chapter of
        Inside Macintosh: Operating System Utilities.


duplicate-bitmap

    formal declaration:
        (duplicate-bitmap bitmap) -> a bitmap
    
    arguments:
        bits    a bitmap pointer
    
    return value:
        a newly created bitmap pointer containing an
        exact duplicate of the bitmap parameter.
        if an error occurs, duplicate-bitmap will return the value NULL.
        
    description:
        duplicate-bitmap creates a copy of the bitmap parameter.

    example application:
        In this example, we make a new bitmap, duplicate it, put it
        on the screen, and then dispose of the resulting bitmaps.
        
        (prog (the-bits extra-bits)
            
           (setf the-bits (new-bitmap 100 200))
           
           ;; normally, we'd draw an image on the bitmap here

           (setf extra-bits (duplicate-bitmap the-bits 50 50 35))
           
           (plot-bitmap extra-bits 0 0 #$srcCopy)
           
           (kill-bitmap the-bits extra-bits))
            
    notes:
        none.


paint-bucket-bitmap

    formal declaration:
        (paint-bucket-bitmap bitmap h v) -> a bitmap
    
    arguments:
        bits     a bitmap pointer
        h         the horizontal position to start painting
        v         the vertical position to start painting
    
    return value:
        a newly created bitmap pointer containing an ones in every
        pixel where paint would not leak out starting from the point
        (h, v).
        if an error occurs, paint-bucket-bitmap will return the value NULL.
        
    description:
        paint-bucket-bitmap works like the paint bucket tool found in
        most graphical applications.  It calls the routine SeedFill
        and to fill in the image information in the resulting bitmap
        pointer.

    example application:
        In this example, we make a new bitmap and create a mask bitmap
        using the paint-bucket-bitmap routine starting at the point (50,50).
        
        (prog (the-bits painted-bits)
            
           (setf the-bits (new-bitmap 100 200))
           
           ;; normally, we'd draw an image on the bitmap here

           (setf painted-bits (paint-bucket-bitmap the-bits 50 50))
           
           (plot-bitmap painted-bits 0 0 #$srcCopy)
           
           (kill-bitmap the-bits painted-bits))
            
    notes:
        paint-bucket-bitmap calls SeedFill.  For further information about
        SeedFill refer to page 3-109 in the QuickDraw Drawing chapter of
        Inside Macintosh: Imaging With QuickDraw.


lasso-bitmap

    formal declaration:
        (lasso-bitmap bitmap) -> a bitmap
    
    arguments:
        bits    a bitmap pointer
    
    return value:
        a newly created bitmap pointer containing an ones in every
        pixel where paint would not leak in from the edges of the
        bitmap.
        if an error occurs, lasso-bitmap will return the value NULL.
        
    description:
        lasso-bitmap works like the lasso bucket tool found in
        most graphical applications.  It calls the routine CalcMask
        and to fill in the image information in the resulting bitmap
        pointer.

    example application:
        In this example, we make a new bitmap and create a mask bitmap
        using the lasso-bitmap routine.
        
        (prog (the-bits lasso-bits)
            
           ;; create a new bitmap
           (setf the-bits (new-bitmap 100 200))
           
           ;; normally, we'd draw an image on the bitmap here

           ;; create a mask for the image
           (setf lasso-bits (lasso-bitmap the-bits 50 50))
           
           ;; plot the mask on the screen
           (plot-bitmap lasso-bits 0 0 #$srcCopy)
           
           ;; recover the storage
           (kill-bitmap the-bits lasso-bits))
            
    notes:
        lasso-bitmap calls CalcMask.  For further information about
        CalcMask refer to page 3-111 in the QuickDraw Drawing chapter of
        Inside Macintosh: Imaging With QuickDraw.


trace-bitmap-edges

    formal declaration:
        (trace-bitmap-edges bitmap) -> a bitmap
    
    arguments:
        bits    a bitmap pointer
    
    return value:
        a newly created bitmap pointer containing containing the original
        image with the edges traced.
        if an error occurs, trace-bitmap-edges will return the value NULL.
        
    description:
        trace-bitmap-edges performs the 'trace edges' command found in
        many graphical applications returning a new bitmap
        containing the traced image..

    example application:
        In this example, we make a new bitmap and create a new bitmap
        containing the traced image.
        
        (prog (the-bits traced-bits)
            
           ;; create a new bitmap
           (setf the-bits (new-bitmap 100 200))
           
           ;; normally, we'd draw an image on the bitmap here

           ;; create a mask for the image
           (setf traced-bits (trace-bitmap-edges the-bits))
           
           ;; plot the new image on the screen
           (plot-bitmap traced-bits 0 0 #$srcCopy)
           
           ;; recover the storage
           (kill-bitmap the-bits traced-bits))
            
    notes:
        none.


equal-bitmaps

    formal declaration:
        (equal-bitmaps bitmap-a bitmap-b) -> T or NIL
    
    arguments:
        a    a bitmap pointer
        b    a bitmap pointer
    
    return value:
        T or NIL
        
    description:
        returns T if the two bitmaps are the same size and
        contain the same image content.  returns NIL if either
        bitmap is NULL.

    example application:
        In this example, we make a new bitmap and create a two bitmaps
        and compare them by calling equal-bitmaps
        
        (prog (bitmap-one bitmap-two)
            
           ;; make some bitmaps
           (setf bitmap-one (new-bitmap 100 200))
           (setf bitmap-two (new-bitmap 100 200))
           
           ;; normally, we'd draw some images on the bitmaps here

           (if (equal-bitmaps bitmap-one bitmap-two)
              (princ "the bitmaps, they are the same!")
              (princ "the bitmaps, they are not the same!"))
           (terpri)
           
           ;; recover the storage
           (kill-bitmap bitmap-one bitmap-two))
            
    notes:
        equal-bitmaps takes into account that either bitmap may have
        different rowBytes values, and the possibility that garbage
        values may be stored in the unused bits off to the right
        of the boundary rectangle.


picture-to-bitmap

    formal declaration:
        (picture-to-bitmap bitmap) -> a bitmap
    
    arguments:
        pic        a handle to a QuickDraw picture
    
    return value:
        a newly created bitmap pointer containing a black and white
        representation of the image drawn by the quickdraw picture
        parameter.
        if an error occurs, picture-to-bitmap will return the value NULL.
        
    description:
        picture-to-bitmap creates a new bitmap pointer the using the size
        information provided in the QuickDraw picture pointer parameter
        and draws the picture in the bitmap before returning the bitmap.

    example application:
        In this example, we call GetPicture to retrieve a picture from
        a resource file and then we convert it to a bitmap by calling
        the routine picture-to-bitmap
        
        (prog (the-bits the-picture)
            
           ;; get a picture resource
           (setf the-picture (#_GetPicture 128))

           ;; convert it into a bitmap
           (setf the-bits (picture-to-bitmap the-picture))
           
           ;; plot the new image on the screen
           (plot-bitmap the-bits 0 0 #$srcCopy)
           
           ;; recover the storage
           (kill-bitmap the-bits))
            
    notes:
        none.


bitmap-to-picture

    formal declaration:
        (bitmap-to-picture bitmap) -> a picture handle
    
    arguments:
        bits    a bitmap pointer
    
    return value:
        a handle to a QuickDraw picture. 
        if an error occurs, the picture's picFrame will be
        an empty rectangle.
        
    description:
        bitmap-to-picture returns a QuickDraw picture that will draw the
        image stored in the bitmap.  bitmap-to-picture is the inverse
        of picture-to-bitmap

    example application:
        In this example, we create a bitmap and convert it into a QuickDraw
        picture.
        
        (prog (the-bits the-picture)
            
           ;; create a new bitmap
           (setf the-bits (new-bitmap 100 200))
           
           ;; normally, we'd draw an image on the bitmap here

           ;; turn the bitmap into a picture
           (setf the-picture (bitmap-to-picture the-bits))
           
           ;; store the picture to the clipboard or somewhere appropriate
           ...
           
           ;; recover the storage
           (kill-bitmap the-bits))
            
    notes:
        QuickDraw pictures are a good way to store image data.


and-bitmaps

    formal declaration:
        (and-bitmaps bitmap-a bitmap-b) -> a bitmap
    
    arguments:
        a        a bitmap pointer
        b        a bitmap pointer
    
    return value:
        a bitmap pointer containing the logical result of ANDing the
        raster data from bitmap a with the raster data from bitmap b. 
        if an error occurs, NULL is returned.
        
    description:
        and-bitmaps logically ANDs the raster data of two bitmap pointers
        returning a new bitmap pointer containing the result.  The two
        parameter bitmaps must have identical dimensions.

    example application:
        In this example, we create two bitmaps and AND them together creating
        a third bitmap.
        
        (prog (a b c)
            
           ;; create a new bitmap
           (setf a (new-bitmap 100 100))
           (setf b (new-bitmap 100 100))

           ;; normally, we'd draw into the bitmaps here

           ;; and the two bitmaps together
           (setf c (and-bitmaps a b))
           
           ;; plot the new image on the screen
           (plot-bitmap c 0 0 #$srcCopy)
           
           ;; recover the storage
           (kill-bitmap a b c))
        
    notes:
        useful for calculating the intersection of two sets of bits.


or-bitmaps

    formal declaration:
        (or-bitmaps bitmap-a bitmap-b) -> a bitmap
    
    arguments:
        a        a bitmap pointer
        b        a bitmap pointer
    
    return value:
        a bitmap pointer containing the logical result of ORing the
        raster data from bitmap a with the raster data from bitmap b. 
        if an error occurs, NULL is returned.
        
    description:
        or-bitmaps logically ORs the raster data of two bitmap pointers
        returning a new bitmap pointer containing the result.  The two
        parameter bitmaps must have identical dimensions.

    example application:
        In this example, we create two bitmaps and OR them together creating
        a third bitmap.
        
        (prog (a b c)
            
           ;; create a new bitmap
           (setf a (new-bitmap 100 100))
           (setf b (new-bitmap 100 100))

           ;; normally, we'd draw into the bitmaps here

           ;; and the two bitmaps together
           (setf c (or-bitmaps a b))
           
           ;; plot the new image on the screen
           (plot-bitmap c 0 0 #$srcCopy)
           
           ;; recover the storage
           (kill-bitmap a b c))
        
    notes:
        useful for calculating the union of two sets of bits.


xor-bitmaps

    formal declaration:
        (xor-bitmaps bitmap-a bitmap-b) -> a bitmap
    
    arguments:
        a        a bitmap pointer
        b        a bitmap pointer
    
    return value:
        a bitmap pointer containing the logical result of XORing the
        raster data from bitmap a with the raster data from bitmap b. 
        if an error occurs, NULL is returned.
        
    description:
        xor-bitmaps logically XORs the raster data of two bitmap pointers
        returning a new bitmap pointer containing the result.  The two
        parameter bitmaps must have identical dimensions.

    example application:
        In this example, we create two bitmaps and XOR them together creating
        a third bitmap.
        
        (prog (a b c)
            
           ;; create a new bitmap
           (setf a (new-bitmap 100 100))
           (setf b (new-bitmap 100 100))

           ;; normally, we'd draw into the bitmaps here

           ;; and the two bitmaps together
           (setf c (xor-bitmaps a b))
           
           ;; plot the new image on the screen
           (plot-bitmap c 0 0 #$srcCopy)
           
           ;; recover the storage
           (kill-bitmap a b c))
        
    notes:
        useful for calculating the difference of two sets of bits.


complement-bitmap

    formal declaration:
        (complement-bitmap bitmap) -> a bitmap
    
    arguments:
        a        a bitmap pointer
    
    return value:
        a bitmap pointer containing the logical result of complementing the
        raster data from bitmap a. 
        if an error occurs, NULL is returned.
        
    description:
        complement-bitmap returns a new bitmap pointer containing the inverse
        of the raster image contained in the bitmap pointer a.

    example application:
        In this example, we create a bitmap and it's complement.
        
        (prog (a b)
            
           ;; create a new bitmap
           (setf a (new-bitmap 100 100))

           ;; normally, we'd draw into the bitmaps here

           ;; and the two bitmaps together
           (setf b (complement-bitmap a))
           
           ;; plot the new image on the screen
           (plot-bitmap b 0 0 #$srcCopy)
           
           ;; recover the storage
           (kill-bitmap a b))
        
    notes:
        useful for calculating the complement of a set of bits.


test-bitmap-pixel

    formal declaration:
        (test-bitmap-pixel bitmap x y) -> T or NIL
    
    arguments:
        bits     a bitmap pointer
        h        the horizontal position of the pixel to test
        v        the vertical position of the pixel to test
        
    return value:
        T if the pixel is 1, NIL if the pixel is 0.
        
    description:
        test-bitmap-pixel tests the value of the pixel at the location (h,v)
        returning T if the pixel is 1, and NIL if the pixel
        is zero.

    example application:
        In this example, we create a bitmap and test the pixel
        located at (25, 32).
        
        (prog (the-bits)
            
           ;; create a new bitmap
           (setf the-bits (new-bitmap 100 100))

           ;; normally, we'd draw into the bitmaps here

           ;; and the two bitmaps together
           (if (test-bitmap-pixel the-bits 25 32)
              (princ "The pixel has the value one!")
               (princ "The pixel has the value zero"))
           
           ;; recover the storage
           (kill-bitmap the-bits))

    notes:
        attempting to test a point outside of the bitmap's bounds
        will produce unpredictable results.


set-bitmap-pixel

    formal declaration:
        (set-bitmap-pixel bitmap hpos vpos)
    
    arguments:
        bits     a bitmap pointer
        h        the horizontal position of the pixel to set
        v        the vertical position of the pixel to set
    
    return value:
        none.
        
    description:
        set-bitmap-pixel sets the value of the pixel at the location (h,v) to 1.

    example application:
        In this example, we create a bitmap and set the pixel
        located at (25, 32) to the value 1.
        
        (prog (the-bits)
            
           ;; create a new bitmap
           (setf the-bits (new-bitmap 100 100))

           ;; set the pixel
           (set-bitmap-pixel the-bits 25 32)

           ;; and the two bitmaps together
           (if (test-bitmap-pixel the-bits 25 32)
              (princ "The pixel has the value one!")
               (princ "The pixel has the value zero"))
           
           ;; recover the storage
           (kill-bitmap the-bits))

    notes:
        attempting to set a pixel outside of the bitmap's bounds
        will produce unpredictable results and may even crash your
        computer by overwriting something important like the operating
        system or your program or something like that.


clear-bitmap-pixel

    formal declaration:
        (clear-bitmap-pixel bitmap hpos vpos)
    
    arguments:
        bits     a bitmap pointer
        h        the horizontal position of the pixel to set
        v        the vertical position of the pixel to set
    
    return value:
        none.
        
    description:
        clear-bitmap-pixel clears the value of the pixel at the location (h,v)
        to 0.

    example application:
        In this example, we create a bitmap and set the pixel
        located at (25, 32) to the value 0.
        
        (prog (the-bits)
            
           ;; create a new bitmap
           (setf the-bits (new-bitmap 100 100))

           ;; set the pixel
           (clear-bitmap-pixel the-bits 25 32)

           ;; and the two bitmaps together
           (if (test-bitmap-pixel the-bits 25 32)
              (princ "The pixel has the value one!")
               (princ "The pixel has the value zero"))
           
           ;; recover the storage
           (kill-bitmap the-bits))

    notes:
        attempting to clear a pixel outside of the bitmap's bounds
        will produce unpredictable results and may even crash your
        computer by overwriting something important like the operating
        system or your program or something like that.


toggle-bitmap-pixel

    formal declaration:
        (toggle-bitmap-pixel bitmap x y) -> T or NIL
    
    arguments:
        bits     a bitmap pointer
        h        the horizontal position of the pixel to set
        v        the vertical position of the pixel to set
    
    return value:
        a boolean value indicating the state of the pixel
        after the toggle operation.  i.e. if the pixel is
        set to the value 1, T is returned.  If the pixel
        is set to the value 0, NIL is returned.
        
    description:
        BitMapToggle inverts the value of the pixel at the location (h,v)
        returning T if the pixel is set to 1 or NIL if the pixel
        is set to 0.

    example application:
        In this example, we create a bitmap and invert the pixel
        located at (25, 32).
        
        (prog (the-bits)
            
           ;; create a new bitmap
           (setf the-bits (new-bitmap 100 100))

           ;; and the two bitmaps together
           (if (toggle-bitmap-pixel the-bits 25 32)
              (princ "The pixel has the value one!")
               (princ "The pixel has the value zero"))
           
           ;; recover the storage
           (kill-bitmap the-bits))

    notes:
        attempting to toggle a pixel outside of the bitmap's bounds
        will produce unpredictable results and may even crash your
        computer by overwriting something important like the operating
        system or your program or something like that.


with-focused-bitmap

    formal declaration:
        (with-focused-bitmap bitmap {form}*) -> bitmap
    
    arguments:
        bitmap     a bitmap pointer
         {form}*       forms executed that draw into the bitmap
    
    return value:
        the bitmap parameter is returned
        
    description:
        with-focused-bitmap is a macro facility that sets up the drawing
        environment such that any drawing commands in the statement
        following the macro instantiation will draw into the bitmap
        provided as the first parameter.

    example application:
        In this example, we create a bitmap and use the with-focused-bitmap
        macro to do some drawing in it.
        
        (prog (the-bits)
            
           ;; create a new bitmap
           (setf the-bits (new-bitmap 100 100))

           ;; draw into the bitmap
           (with-focused-bitmap (the-bits)
               (#_MoveTo 10 10)
               (#_LineTo 90 90))
           
           ;; recover the storage
           (kill-bitmap the-bits))

    notes:
        none.


plot-bitmap

    formal declaration:
        (plot-bitmap bitmap hpos vpos mode)
    
    arguments:
        bits        a bitmap pointer
        h           the horizontal location where the bitmap is drawn
        v           the horizontal location where the bitmap is drawn
        mode        transfer mode passed to copybits
    
    return value:
        none.
        
    description:
        plot-bitmap provides a simple interface for drawing a bitmap in
        the current grafport.  The bitmap is drawn with the top left corner
        aligned with the point (h,v) using the indicated transfer mode.
        mode is one of:
        #$srcCopy #$srcOr #$srcXor #$srcBic #$notSrcCopy
        #$notSrcOr #$notSrcXor #$notSrcBic #$patCopy #$patOr #$patXor
        #$patBic #$notPatCopy #$notPatOr #$notPatXor #$notPatBic

    example application:
        In this example, we create a bitmap and use the WithBitMap
        macro to do some drawing in it, and then we copy the result
        to the current grafport at the location (75, 23) using the
        plot-bitmap routine.
        
        (prog (the-bits)
            
           ;; create a new bitmap
           (setf the-bits (new-bitmap 100 100))

           ;; draw into the bitmap
           (with-focused-bitmap (the-bits)
               (#_MoveTo 10 10)
               (#_LineTo 90 90))
           
           ;; draw it on the screen
           (plot-bitmap the-bits 75 23 #$srcCopy)

           ;; recover the storage
           (kill-bitmap the-bits))

    notes:
        plot-bitmap calls CopyBits.


string-to-bitmap

    formal declaration:
        (string-to-bitmap the-string &optional the-font-spec) -> a bitmap
    
    arguments:
        the-string           a string
        the-font-spec      an optional font specification

    return value:
        a bitmap pointer
        
    description:
        string-to-bitmap converts the string pointed to by s into a bitmap
        drawing the string onto an appropriately sized bitmap for the
        given font specification  string-to-bitmap is useful for
        converting strings to bitmap so rotation can be applied with
        rotate-bitmap-left or rotate-bitmap-right before it is displayed.
        string-to-bitmap preserves the current grafport.  if
        the-font-spec is not provided, the system font will be used.

    example application:
        In this example, we create a bitmap pointer containing
        the string "Hello World" (using bold, underlined,
        24 point geneva font), rotate it 90 degrees to the
        right, and draw the result in the current grafport
        at the location (110,34) using the plot-bitmap routine.
        
        (prog (the-bits rotated-bits)
            
            ;; create a new bitmap
            (setf the-bits (string-to-bitmap "Hello World" '("Geneva" 24 :bold :underline)))
            
            ;; rotate the string
            (setf rotated-bits (rotate-bitmap-right the-bits))
            
            ;; draw it on the screen
            (plot-bitmap rotated-bits 110 34 #$srcCopy)
            
            ;; recover the storage
            (kill-bitmap the-bits rotated-bits))

    notes:
        none.


get-bitmap-width

    formal declaration:
        (get-bitmap-width bitmap) -> the width
    
    arguments:
        bitmap           a bitmap

    return value:
        the width of the bitmap
        
    description:
        get-bitmap-width is a convenience routine that returns
        the width of a bitmap.

    notes:
        none.


get-bitmap-height

    formal declaration:
        (get-bitmap-height bitmap) -> the height
    
    arguments:
        bitmap           a bitmap

    return value:
        the height of the bitmap
        
    description:
        get-bitmap-width is a convenience routine that returns
        the height of a bitmap.

    notes:
        none.


file BitMapLisp.txt Copyright (C) 1996 by John Montbriand.  All Rights Reserved.

end of file